参数和返回值

Rive React API 参考。

Hook

useRive

useRive Hook 是接入 Rive 运行时的推荐方式，可实现完全控制，尤其是在使用 Rive 状态机时。以下是可传入的参数和返回值。

useRive(riveParams: UseRiveParameters, opts: UseRiveOptions): RiveState

• riveParams - 请参见下方传入到 Web 运行时 Rive 对象实例化的参数集。可以传入 null 和 undefined 来条件显示 .riv 文件
• opts - （可选） 请参见下方 rive-react 特有的选项集

参数

UseRiveParameters

这些参数大多来自底层 Web 运行时 Rive 对象的配置项，但不包括提供 canvas 元素。有关可在此对象中提供的所有参数，请参见 Rive 参数。

如果你在参数中提供 onLoad 回调，你可能还无法访问 rive 实例。React 运行时内部使用 onLoad 来通过 rive 实例设置状态，因此当回调到达消费者提供的回调时可能尚未填充。我们建议使用 useEffect 代替 onLoad 来可靠地使用 rive 实例。在未来的 Web 运行时版本中，我们可能会在回调参数中提供 rive 实例，以便你在此处提供 onLoad。

UseRiveOptions

• useDevicePixelRatio - （可选） 如果为 true，Hook 将根据 devicePixelRatio 缩放动画的分辨率。默认为 true。注意：需要将 setContainerRef ref 回调传递给包裹画布元素的元素。如果你使用 RiveComponent，这将自动完成
• fitCanvasToArtboardHeight - （可选） 如果为 true，画布将根据画板高度调整大小。默认为 false
• useOffscreenRenderer - （可选） 如果为 true，Rive 实例将共享（或创建，如果不存在）一个离屏 WebGL 上下文。这使你可以在同一屏幕上显示多个 Rive 动画，以解决浏览器对多个并发 WebGL 上下文的某些限制。如果为 false，每个 Rive 实例将拥有自己的专用 WebGL 上下文，你可能需要注意上述浏览器限制。我们建议不要更改此默认属性，这样你就不必管理 WebGL 上下文。销毁 React 组件并不能保证浏览器清理挂载画布时创建的 WebGL 上下文。仅在使用 @rive-app/react-webgl2 时相关。默认为 true

返回值

RiveState

• canvas - Rive 实例渲染到的 Canvas 元素
• container - Rive 实例渲染到的画布的容器元素
• setCanvasRef - 要传递给 canvas 元素的 Ref 回调
• setContainerRef - 要传递给画布容器元素的 Ref 回调。这是可选的，但是如果不使用，Hook 在窗口大小调整时将不会自动将画布调整到其外部容器
• rive - 从 Web 运行时新创建的 Rive 实例
• RiveComponent - 在 DOM 中渲染 Rive 实例的 JSX 元素

在大多数情况下，你只需要从 useRive Hook 中获取 RiveComponent 和 rive 返回值。只有在需要自己控制画布/容器元素时，才需要设置画布 ref 和容器 ref。

useStateMachineInput

useStateMachineInput Hook 是获取 Rive 状态机输入引用的推荐方式，用于读取输入值和设置（或触发）它们。以下是可传入的参数和返回值。

useStateMachineInput(rive: Rive | null, stateMachineName?: string, inputName?: string, initialValue?: number | boolean): StateMachineInput | null

由于需要 rive 实例先解析，返回值（状态机输入）可能不会立即可用。你可能需要使用 useEffect 来监听 rive 实例和 useStateMachineInput Hook 返回值何时有值

参数

• rive - 第一个参数是实例化的 Rive 对象 - 可通过 useRive Hook 获取
• stateMachineName? - （可选） 要从中获取输入的状态机名称
• inputName? - （可选） 要获取引用的单个状态机输入的名称
• initialValue? - （可选） 在输入上设置的初始值

返回值

此 Hook 返回 StateMachineInput 的默认实例。

StateMachineInput

• name（获取）- 访问输入的名称
• value（获取和设置）- 访问输入的值，并通过此属性设置输入的值
• fire() - 触发触发器输入

请参见输入页面了解更多此 Hook 的用法。

useResizeCanvas

useResizeCanvas Hook 是一个可选的实用 Hook，用于将 <canvas> 元素调整为其父容器元素的大小，同时重置画布相应的表面积大小。当你想在 React 应用中使用 Web JS 运行时（而不是使用 useRive Hook 来渲染 Rive）时，这个 Hook 非常有用，但你仍然希望 <canvas> 能自动缩放到其父容器。

此 Hook 已在 Rive React 运行时内部使用，因此如果你使用 useRive Hook 或默认导出的 <RiveComponent /> 来渲染 Rive，你不需要自己使用此 Hook。

useResizeCanvas(resizeProps: UseResizeCanvasProps): void

• resizeProps - 请参见下方要在此对象参数上设置的属性集

参数

UseResizeCanvasProps

• riveLoaded: boolean - 如果为 true，Rive 实例已创建且 Rive 文件已解析。这确保 Hook 不会过早缩放 <canvas> 元素。默认为 false
• canvasRef: MutableRefObject<HTMLCanvasElement | null> - Rive 将渲染到的 <canvas> 元素的 React Ref
• containerRef: MutableRefObject<HTMLElement | null> - 画布父容器元素的 React Ref
• onCanvasHasResized?: () => void（可选）在画布因父容器大小调整而被调整后调用的回调。在此处你可以重置 Rive 渲染器的布局尺寸以指定画布新的最小/最大边界。
  • 使用高级 JS 运行时，这可能是一个简单的 rive.resizeToCanvas() 调用
  • 使用低级 JS 运行时，这可能是调用渲染器的 .align() 方法，传入布局和画布的最小/最大 X/Y 值。
• options?: Partial -（可选）传递给 useRive Hook 的选项（请参见上文 UseRiveOptions）
• artboardBounds?: Bounds -（可选）画板的 AABB 边界；仅当 options.fitCanvasToArtboardHeight 设置为 true 时才需要提供。

useRiveFile

useRiveFile Hook 旨在组件内初始化和管理 RiveFile 实例。它根据提供的源参数（URL 或 ArrayBuffer）设置 RiveFile，并确保在组件卸载或输入变化时进行适当的清理，以避免内存泄漏。

此 Hook 的主要优势在于，它允许你创建一个可在多个组件间复用的 RiveFile 实例，无需每次都重新从 src URL 获取或从 buffer 重新加载。这通过消除冗余的网络请求和加载时间来提升性能，尤其在从同一源创建多个 Rive 实例时效果显著。与直接将 buffer 和 src 参数传递给 useRive Hook 不同（后者仍需要在底层解析以创建 RiveFile 对象），此 Hook 返回一个已解析的 RiveFile 对象，包括所有已加载的资源。

useRiveFile(params: UseRiveFileParameters): RiveFileState

参数

UseRiveFileParameters

• src? - （可选） 有两种使用 src 的可选方式：通过 URL 指向 .riv 文件，或通过指向公共 .riv 资源的路径。必须提供 src 或 buffer 之一。
  • URL - 如果你将 .riv 托管在某个可公开访问的存储桶/CDN（如 AWS、GCS 等），你可以在此处传入 URL。
    • 或者，使用 ES6，你可以将 .riv 文件导入为 data URI。根据你的打包加载器，你可能需要使用插件（如 Webpack 的 url-loader）来正确解析和加载 .riv 文件为 data URI 字符串。请参见此项目作为如何设置的基本示例
  • 公共资源路径 - 这是指向应用程序中打包的 .riv 公共资源的字符串路径。注意，这不是从当前 JS 文件位置到资源的相对路径。将 .riv 视为应用程序中打包的任何其他资源，如图片或字体。如果你的 JS 在 Web 应用程序的根目录编译和运行，你必须指定从根目录到资源位置的路径。例如，如果你的资源在 /public/foo.riv，而你的 JS 从根目录 / 运行，你应在此属性中指定：src: '/public/foo.riv'。
• buffer? - （可选） 包含 .riv 文件原始字节的 ArrayBuffer。必须提供 src 或 buffer 之一。
• enableRiveAssetCDN? - （可选） 允许运行时自动加载托管在 Rive CDN 中的资源。默认启用。

返回值

RiveFileState

• riveFile - RiveFile 实例。在文件加载完成前为 null。
• status - 文件加载过程的状态，可以是 idle、loading、failed 或 success。

组件

<RiveComponent />

RiveComponent 默认导出和从 useRive Hook 返回的 RiveComponent 都要在组件的 JSX 中渲染。如前所述，所有可以传递给 canvas 元素的属性和事件处理程序也可以传递给 Rive 组件并以相同方式使用。

需要注意的是，设置在组件上的 style/className 属性将传递到包裹的 <div> 元素，而不是底层的 <canvas> 本身。原因是包裹的 <div> 元素为你处理大小调整和布局，因此所有样式都应传递到此元素。

<canvas> 元素仍将接收传入组件的其他任何属性，如 aria-* 属性、role 等。你还可以在组件内设置子内容，用于 <canvas> 元素无法显示的降级场景。